Replication Command Forwarding
The Common Alarm Service (CAS) is able to pass or forward commands (such as acknowledgment requests) by writing the commands in XML format to a specified location on the replication server. The CAS will validate the request and if command forwarding is configured, will write out the command and the associated information to an XML file. During startup the CAS will process and delete these files as necessary. A client program such as CygNet Studio or the CAS Alarm Control will receive the same response as if the replicated CAS was not in replicated mode. Replication command forwarding details can be viewed in the service Console screen.
See the following subsections below for more information:
- Configuring Replication Command Forwarding
- XML File Name Format
- XML File Format
- Directory Maintenance
- Service Console Screen
Configuring Replication Command Forwarding
In order for the CAS to forward a command the following configuration conditions must be met:
- The CAS is in replication mode.
- The replicated server is configured and running.
- The associated CAS service configuration file (Cas.cfg), on the replicated server, has the REPL_FORWARD_DIRECTORY keyword configured, and this will be created during startup if necessary.
- The CAS has the ability to write to the directory specified in the REPL_FORWARD_DIRECTORY keyword.
- The user sending the request is authorized (has appropriate security) for this request if the service was not in replication mode.
- If the Cas.cfg is modified the CAS must be stopped and restarted in order for the changes to take effect.
Upon receiving a validated and authorized request, if the CAS is forwarding commands, the CAS will write the request to the specified directory in the XML format.
Configuration Keywords
The following table contains descriptions for the service configuration keywords required to enable replication command forwarding in the Cas.cfg file.
| Keyword | Description |
|---|---|
|
REPL_FORWARD_DIRECTORY |
If the service is in replication mode and this keyword is defined, then a setpoint command issued to the source service will be written out as an XML file (ForwardCmds_CVS_Site.Service_######.xml) and saved in the specified directory. Note that setting this keyword does not write the value to the source service. The user will need to evaluate the command and decide whether to modify a point’s current value using a setpoint command on the source service. If this keyword is empty or commented out, then Replication Command Forwarding is disabled. See Replication Command Forwarding for more information. |
|
REPL_FORWARD_MAX_FILES |
The maximum number of files in the directory specified by the keyword REPL_FORWARD_DIRECTORY. Once this number is reached, the service will attempt to begin deleting the oldest files. Must be in the range 10-1000. See Replication Command Forwarding for more information. |
XML File Name Format
Replication forwarding command file names are designed to support different service types while providing quick identification of the creating service type and name. Forwarded commands will be stored in a file with the following name:
|
ForwardCmdS_[SERVICE_TYPE]_[SITE.SERVICE]_[SEQUENCE_NUMBER][QUALIFIER].xml |
where
- [SERVICE_TYPE] is the type of service, in this case "CAS."
- [SITE.SERVICE] is the site.service of the CAS.
- [SEQUENCE_NUMBER] is a zero-padded numerical number between 000001 and 999999. This will either start at 1 or the next number in the forwarding directory as determined at service startup.
- [QUALIFIER] should never appear under normal operations, but if for some reason a file with the next sequence number already exists, this will be added in the form -# where # is a single digit in the range 1-5.
For example:
For a CAS with a name of MYSITE.CAS will create the first command file as: ForwardCmds_CAS_MYSITE.CAS_000001.xml, and the 123rd file as: ForwardCmds_CAS_MYSITE.CAS_000123.xml
If a file with the name ForwardCmds_CAS_MYSITE.CAS_000123.xml already exists, then the file name used would be ForwardCmds_CAS_MYSITE.CAS_000123-1.xml. This should not occur in normal operations.
XML File Format
The XML format used for Replication Command Forwarding is designed to support additional service and command types. The XML takes the following format:
|
<ForwardingCmds …> <CasChangeAlarm …> < AlarmRec …/> <CasChangeAlarm …> < AlarmRec …/> <CasChangeAlarm …> < AlarmRec …/> </ForwardingCmds> |
ForwardingCmds Node Attributes
This XML node is the root node of the Command Forwarding file.
| Attribute | Description | Value Options |
|---|---|---|
|
CmdType |
The type of commands this file contains. Each of this nodes direct child nodes should have this node tag. |
CasChangeAlarm is the only supported command for the CAS. |
|
Comment |
A comment from the user. |
String |
|
FromService |
The service creating the file. |
[domain]site.service |
|
ServiceType |
The service type of the service forwarding the command. |
String. For example "CAS for the CAS |
|
TimeStampUTC |
The time the XML file was created. |
OLE date in floating-point format, UTC |
|
ToService |
The service the command should be forwarded to. |
[domain]site.service |
|
UserId |
The User Id of the user that originated the command request. |
String |
CasChangeAlarm Node Attributes
This XML node is the root node of the CAS Change Alarm command.
| Attribute | Description | Value Options |
|---|---|---|
|
ChangeType |
The type of change requested. |
String: "ACK", "HIDE", "UNHIDE", "CLEAR", "FORCE" |
AlarmRec Node Attributes
This XML node is the root node for the current Alarm Record in the CAS at the time the command was forwarded.
| Attribute | Description | Value Options |
|---|---|---|
|
alarmack |
Is the alarm acknowledged? |
0 = False, otherwise True |
|
alarmcategory |
The alarm category from the point record. |
The TRS entry, not the description. |
|
alarmcleared |
Is the alarm cleared? (always zero for CAS) |
0 = False, otherwise True |
|
alarmpriority |
The priority of the alarm. |
Numeric: 0-99 |
|
alarmprioritycat |
The priority category of the alarm. |
Numeric: 0-7 |
|
alarmrecversion |
The version of the alarm record. |
Floating-point number |
|
facilityid |
The facility of the point. |
String: Facility Id |
|
hidden |
Is the alarm hidden? |
0 = False, otherwise True |
|
highestpriority |
The highest priority since the point was added to the CAS. |
Numeric: 0-99 |
|
highestpriorityunack |
The highest priority since the point was last acknowledged. |
Numeric: 0-99 |
|
pointid |
The short point ID of the point. |
String |
|
pointidlong |
The long point ID of the point. |
String |
|
reporttime |
The time the alarm was reported to the CAS. |
OLE Date in floating-point format, UTC |
|
service |
The service of the point. |
String |
|
setreset |
The alarm is set? |
0 = Reset, otherwise Set |
|
site |
The site of the point. |
String |
|
suppression |
Is the alarm suppressed? |
0 = False, otherwise True |
|
timestamp |
The timestamp of the point real-time record when the alarm was reported to the CAS. |
OLE Date in floating-point format, UTC |
|
uniformdatacode |
The UDC of the point. |
String |
Directory Maintenance
Upon startup, the CAS will attempt to create the forwarding directory if the service is in replication mode and the REPL_FORWARD_DIRECTORY keyword is configured. This will only be attempted at startup.
The CAS will prevent the number of files in the forwarding directory from growing unbounded. The maximum number of files in this directory is specified in the associated Cas.cfg with the REPL_FORWARD_MAX_FILES keyword.
When the CAS runs its maintenance routine, it will check the number of files in the directory. If the number of files exceeds the maximum number allowed, the CAS will begin to delete the oldest files until the number of files is 10% less than the maximum number of files. The Directory Maintenance routine runs at CAS startup, and after each time a command has been forwarded, unless the routine already been run in the previous 10 minutes.
Service Console Screen
The CAS Service Console Screen (F2: System) provides a visual indication of the forwarding: whether replication command forwarding is configured, the command forwarding directory, the maximum amount of files for the directory, the time of the last command forwarding, and any errors encountered when writing to the directory or during directory maintenance.
